/*
 * Copyright © 2002-2011 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

using System.Data;

namespace Spring.Data.Common;

/// <summary>
/// Factory interface to create provider specific ADO.NET objects.
/// </summary>
public interface IDbProvider
{
    /// <summary>
    /// Returns a new command object for executing SQL statments/Stored Procedures
    /// against the database.
    /// </summary>
    /// <returns>An new <see cref="IDbCommand"/></returns>
    IDbCommand CreateCommand();

    /// <summary>
    /// Returns a new instance of the providers CommandBuilder class.
    /// </summary>
    /// <remarks>In .NET 1.1 there was no common base class or interface
    /// for command builders, hence the return signature is object to
    /// be portable (but more loosely typed) across .NET 1.1/2.0</remarks>
    /// <returns>A new Command Builder</returns>
    object CreateCommandBuilder();

    /// <summary>
    /// Returns a new connection object to communicate with the database.
    /// </summary>
    /// <returns>A new <see cref="IDbConnection"/></returns>
    IDbConnection CreateConnection();

    /// <summary>
    /// Returns a new adapter objects for use with offline DataSets.
    /// </summary>
    /// <returns>A new <see cref="IDbDataAdapter"/></returns>
    IDbDataAdapter CreateDataAdapter();

    /// <summary>
    /// Returns a new parameter object for binding values to parameter
    /// placeholders in SQL statements or Stored Procedure variables.
    /// </summary>
    /// <returns>A new <see cref="IDbDataParameter"/></returns>
    IDbDataParameter CreateParameter();

    /// <summary>
    /// Creates the name of the parameter in the format appropriate to use inside IDbCommand.CommandText.
    /// </summary>
    /// <remarks>In most cases this adds the parameter prefix to the name passed into this method.</remarks>
    /// <param name="name">The unformatted name of the parameter.</param>
    /// <returns>The parameter name formatted foran IDbCommand.CommandText.</returns>
    string CreateParameterName(string name);

    /// <summary>
    /// Creates the name ofthe parameter in the format appropriate for an IDataParameter, i.e. to be
    /// part of a IDataParameterCollection.
    /// </summary>
    /// <param name="name">The unformatted name of the parameter.</param>
    /// <returns>The parameter name formatted for an IDataParameter</returns>
    string CreateParameterNameForCollection(string name);

    /// <summary>
    /// Return metadata information about the database provider
    /// </summary>
    IDbMetadata DbMetadata
    {
        get;
    }

    /// <summary>
    /// Connection string used to create connections.
    /// </summary>
    string ConnectionString
    {
        set;
        get;
    }

    /// <summary>
    /// Extracts the provider specific error code as a string.
    /// </summary>
    /// <param name="e">The data access exception.</param>
    /// <returns>The provider specific error code</returns>
    string ExtractError(Exception e);

    /// <summary>
    /// Determines whether the provided exception is in fact related
    /// to database access.  This can be provider dependent in .NET 1.1 since
    /// there isn't a common base class for ADO.NET exceptions.
    /// </summary>
    /// <param name="e">The exception thrown when performing data access
    /// operations.</param>
    /// <returns>
    /// 	<c>true</c> if is a valid data access exception for the specified
    /// exception; otherwise, <c>false</c>.
    /// </returns>
    bool IsDataAccessException(Exception e);
}
